# 11 - 配置与内存系统

## 一、配置系统

### 配置层级（优先级从高到低）

```
1. 组织策略 (Policy)           ← 最高优先级，不可覆盖
2. 命令行标志 (Flag)
3. 用户配置 (~/.claude/settings.json)
4. 本地配置 (.claude/settings.local.json)
5. 项目配置 (.claude/settings.json)    ← 最低优先级，受限制
```

### 项目配置的限制

项目配置 (`.claude/settings.json`) 放在 Git 仓库中供团队共享，但它**不能**做所有事——权限规则中只能添加 `deny` 和 `ask`，不能添加 `allow`。这防止恶意仓库自动授予自己权限。

### 设置 Schema

配置使用 Zod schema 校验 (`src/schemas/`)：

```typescript
// 概念简化
const settingsSchema = z.object({
  permissions: z.object({
    allow: z.array(permissionRuleSchema),
    deny: z.array(permissionRuleSchema),
  }),
  hooks: z.record(hookSchema),
  env: z.record(z.string()),
  model: z.string().optional(),
  // ...
})
```

校验在启动时执行。如果配置解析失败，抛出 `ConfigParseError` 并显示错误对话框。

---

## 二、内存系统 (memdir/)

### CLAUDE.md — 项目记忆

Claude Code 的持久化记忆通过 `CLAUDE.md` 文件实现：

| 位置 | 作用域 | 说明 |
|------|--------|------|
| `~/CLAUDE.md` | 全局 | 用户级偏好，所有项目共享 |
| `<项目根>/CLAUDE.md` | 项目 | 项目级指令 |
| `<项目根>/.claude/CLAUDE.md` | 项目 | 项目级指令（替代位置） |
| `<子目录>/CLAUDE.md` | 目录 | 目录级指令（延迟加载） |

### 加载策略

```
启动时立即加载（Eager）:
  ~/CLAUDE.md
  <项目根>/CLAUDE.md
  <项目根>/.claude/CLAUDE.md

工作时按需加载（Lazy）:
  <子目录>/CLAUDE.md — 当 Agent 进入该目录时加载
```

延迟加载的 CLAUDE.md 作为 `AttachmentMessage` 注入对话：

```typescript
// 去重逻辑
loadedNestedMemoryPaths?: Set<string>
// 防止同一 CLAUDE.md 被多次注入
```

### 自动记忆提取

```
services/extractMemories/
```

Claude Code 可以自动从对话中提取有价值的信息保存为记忆。例如，如果用户多次纠正 Claude 的某个行为，系统会自动提取这个偏好。

### 记忆目录结构

```
~/.claude/
├── settings.json          # 用户配置
├── memory/                # 持久化记忆
│   ├── user/              # 用户级记忆
│   ├── feedback/          # 反馈记忆
│   └── project/           # 项目级记忆
└── keybindings.json       # 快捷键配置
```

---

## 三、Hooks 系统（生命周期钩子）

**注意**：这里的 Hooks 不是 React Hooks，而是 Claude Code 的**生命周期钩子系统**——允许用户在特定事件发生时执行自定义脚本。

### 配置方式

在 `settings.json` 中定义：

```json
{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": "echo 'Bash tool is about to be used'"
          }
        ]
      }
    ],
    "PostToolUse": [...],
    "SessionStart": [...],
    "PreCompact": [...],
    "PostCompact": [...]
  }
}
```

### Hook 事件类型

| 事件 | 触发时机 |
|------|----------|
| **PreToolUse** | Tool 执行之前 |
| **PostToolUse** | Tool 执行之后 |
| **PreCompact** | 上下文压缩之前 |
| **PostCompact** | 上下文压缩之后 |
| **Notification** | 通知触发时 |
| **Stop** | 停止时 |
| **SubagentStop** | 子 Agent 停止时 |
| **SessionStart** | 会话开始 |
| **SessionPause** | 会话暂停 |
| **SessionResume** | 会话恢复 |
| **CompactBoundary** | 压缩边界 |
| **WorktreeCreate** | Worktree 创建时 |
| **WorktreeRemove** | Worktree 删除时 |

### Hook 匹配器

Hook 通过 `matcher` 字段指定触发条件：

```json
{
  "matcher": "Bash",           // 匹配 Bash Tool
  "matcher": "Bash(git *)",    // 匹配 git 开头的 Bash 命令
  "matcher": "FileEdit",       // 匹配文件编辑
}
```

### Hook 类型

| 类型 | 说明 |
|------|------|
| `command` | 执行 Shell 命令 |
| `prompt` | 生成 LLM 提示 |
| `agent` | 触发 Agent |
| `http` | HTTP 回调 |
| `callback` | 内部回调函数 |

### Hook 执行

- 同一事件的多个 Hook **并行执行**
- 每个 Hook 有独立的超时时间
- `PreToolUse` Hook 可以返回：
  - `approve` — 自动批准 Tool
  - `deny` — 拒绝 Tool
  - `updatedInput` — 修改 Tool 输入

### 安全约束

Hook 需要**信任**才能执行。项目级 Hook（来自 `.claude/settings.json`）需要用户确认信任后才生效。

---

## 四、插件系统 (`plugins/`)

### 插件 vs 技能

| | 插件 (Plugin) | 技能 (Skill) |
|---|---|---|
| 作用 | 扩展 Claude Code 核心功能 | 提供特定领域能力 |
| 加载时机 | 启动时 | 按需 |
| 实现 | 代码包 | 提示 + 配置文件 |

### 内置插件

内置在源码中的插件，提供基础功能扩展。

### 技能系统 (`skills/`)

技能是轻量级的扩展点：

```
技能目录/
├── my-skill/
│   ├── index.md          # 技能说明（frontmatter + 提示）
│   └── files/            # 附带文件
```

技能文件的 frontmatter：

```yaml
---
name: my-skill
description: 做某件事
trigger: 当用户提到 X 时
---
```

技能通过 `SkillTool` 被 Claude 调用，或作为 `/my-skill` 斜杠命令被用户调用。

---

## 五、会话持久化

### Session Storage

```typescript
import { flushSessionStorage, recordTranscript } from './utils/sessionStorage.js'
```

会话数据保存到磁盘，支持 `/resume` 恢复之前的对话。

### 保存内容

- 完整消息历史
- Tool 使用记录
- 文件状态快照
- Token 使用统计
- 上下文元数据

### 文件历史

```typescript
import { fileHistoryEnabled, fileHistoryMakeSnapshot } from './utils/fileHistory.js'
```

可选的文件历史追踪，记录 Claude 修改过的每个文件版本，支持回滚。